Librarian
User Manual – Version 1.0
September 2020
Developers/Contributors:
Special thanks to those who submitted user stories:
Additional thanks to our beta testers and those who submitted bugs:
And lastly, a huge appreciation to the entire Empress Effects team for the support and assistance in developing this application!
This software is distributed under GNU General Public License 3.0. Please familiarize yourself with the Terms & Conditions of copyleft licenses like GPL (and others) here: https://www.gnu.org/licenses/gpl-3.0.en.html. ZOIA and its patch binary format are a trademark of Empress Effects, Inc and are used with permission. Neither the developers nor Empress Effects, Inc. are liable for any issues caused or raised by the use or modification of this application. By using the application you agree to these terms. All source code, documentation, issue reports, and release candidates are hosted via Github: https://github.com/meanmedianmoge/zoia_lib.
Acknowledgements 1
EULA 1
Table of Contents 2
Welcome 3
Loading the App
Tabs
PatchStorage View 4
Patch Metadata
Searching
Downloads
Refresh Patch List
Local Storage View 6
Check for Updates
Export and Delete
Version Histories
Editing Patch Metadata
Patch Visualizer
SD Card View 10
Selecting the SD Location
Managing SD Directories
Moving Patches
Import Functions
Bank View 12
Local Storage table
Moving Patches to a Bank
Bank Operations
Additional Features 14
File Menu
Sort Menu
Options Menu
Help Menu
Documentation
Changelog 16
New Features
Bug Fixes
Known Issues
Future Plans 17
Welcome to the ZOIA Librarian! The Librarian aims to make using ZOIA much easier. Whether you are a major patch creator or a general ZOIA user, the ZOIA Librarian has features that can help anyone organize and manage their patches.
After you have downloaded and installed the ZOIA Librarian, the application can be launched from a single executable on Windows or a single application file on OSX. Double-clicking on the ZOIALibrarian.1.0.exe or ZOIALibrarian.1.0.app file will start the app. You will be greeted with a brief splash screen as the application loads.
^
If this is your first time launching the application, the start-up process will take longer than usual, as all patch information is retrieved from PatchStorage. Subsequent start-ups will not need to retrieve as much information, significantly improving the loading time.
The application is split into 4 main tabs:
These tabs allow you to navigate between different features of the Librarian. The following sections of this manual will focus on each tab and explain the features specific to that tab:
PatchStorage ViewSelecting a patch by clicking on the circle beside the patch title will populate the right side of the screen with additional information about the patch. This displays the author and license, the like, view, and download counts, and can even include a clickable preview link (if the author has included one):
^
Above the table on the left, there is a search bar. You can search for patches by title, tag, category, and date in the PatchStorage View tab. To initiate a search, enter the query you want to search for and hit Enter/Return. For example, if you wanted to find all the patches that have “game” in its title, tags, or category:
^
Downloading patches is as easy as hitting the download button to the right of the patch you want to download. Once the download is complete, the button will disappear. This is to make sure you do not accidently download the same patch twice. Even on subsequent launches of the application, if you have previously downloaded a patch and it still exists within a Librarian, no button will exist:
^
To the right of the search bar, there is a “Refresh Patches” button that will allow you to refresh the patch list to reflect the patches available on Patchstorage. The app also updates this list each time it is opened. If you refresh the list, a pop-up will let you know when it has finished:
Above the search bar is the “Download All Patches” button, which will download all currently hosted patches from PatchStorage. Note that this download process is very time-consuming.
You can view all the patches you have downloaded by switching to the Local Storage tab, which will be covered in the next section.
At first glance, the Local Storage tab will look very similar to the previous tab. However, there are many additional options to explore. Searching behaves the same as it does in the PatchStorage tab, except you can now also search for patches by author. Additionally, there are two new buttons to the left and right of the search bar. A “Back” button and a “Check for updates” button. The “Back” button will initially be inaccessible.
^
The “Check for updates” button will automatically check all the patches you have within the Librarian to see if they have been updated on PatchStorage. If the patches have been changed, these updates will automatically be retrieved and saved. Most of the time, however, this is the message you will get when clicking the button:
Within the patch table, there are two new buttons: Export and Delete. To delete a patch from the Librarian, click the “X” button beside the patch.
When you click on the export button for the first time, the message below is most likely what you will see. If you click “OK”, you will be able to select the SD card used for patch transfer. Alternatively, to select your SD Card location, look for the “File” option on the taskbar at the top of the screen, click it, and then click “Specify SD Card Location”. Please note that exporting from the Local Storage tab will export to a folder called “to_zoia” by default. You will be able to see this folder and its patches in the SD Card tab.
Exported patches will be placed into the slot you specify. You will be warned if you are trying to export to a slot that is already occupied by another patch. Otherwise, the export will take place and you will be able to find the patch in the directory named “to_zoia” on your SD card.
For certain patches, the Export button is inaccessible - this is because these originated as zip files with multiple patches or versions. The Librarian unzips these as they are downloaded and stores them as a versioned patch. To access the Version History view, click on the circle to the left of any patch that has “[Multiple versions]” in its name. Clicking “X” on this row will delete all patches within the version history.
Upon entering the Version History view for a patch, you can individually export specific versions and delete them. To exit this view, click the “Back” button.
The Local Storage tab also offers edit functionality for patches you’ve downloaded or imported. To modify the patch tags or categories, simply double-click on the cell you wish to edit and start typing. Once you have finished, simply click off the cell or hit Enter/Return:
The right-side upper panel displays the patch metadata, which can also be edited. To do so, first select a patch on the left-hand side of the screen by clicking on the circle to the left of its name. Next, make the edits you wish to add or remove:
Once you are done, click the “Update Patch Notes” above to save these changes. A couple notes about making edits to patch notes or information:
The last major feature in the Local Storage tab is the patch visualizer. Located in the right-side lower panel, the visualizer offers a way to explore the layout of a patch before loading it onto your ZOIA. There are two primary types of information present in the visualizer:
Please note that certain patches may fail to display in the visualizer panel - this is likely due to them being saved on deprecated ZOIA firmware. If you find a patch that doesn’t display a visualization as-is, an easy fix is to load it onto your ZOIA, save with a more recent firmware (preferably 1.13), and re-import (deleting the old version in the process). This feature has been a huge time investment and we are extremely happy to offer it in the first official release of the ZOIA Librarian.
Now that we have explored the Local Storage tab, it’s time to move on the SD Card tab!
The SD Card tab gives you a look into the directories located on the SD card you have specified. In case you have not specified your SD card yet, look for the “File” option towards the top left of the screen, click it, and then click “Specify SD Card Location”:
After selecting your SD card location, this is the screen you will be presented with:
The upper portion of the screen lists all the folders located on the SD card. You can expand these folders if need be by clicking on the arrow to the left of each folder. Clicking a folder will populate the table with patches.
You can move patches within the folder by dragging and dropping them into different slots on the SD card. Multiple selections can be done with Shift or Ctrl/Cmd macros. You can also remove a patch from your SD card by clicking the “X” button in each row, or completely remove a directory from your SD card by selecting “Delete Selected Item 
Above”. This button will trigger a confirmation window:
The most important features in the SD Card tab are related to patch importing, of which there are 3 options. The first is achieved by clicking “Click me to Import” next to a patch in the above table. The second and third deal with mass importing of multiple patches at once - in one of two ways: import multiples as individual patches or import multiples as a versioned patch.
During the import process, the Librarian will attempt to merge with any patches you have in your Local Storage or ones currently hosted on PatchStorage (bringing along the metadata in the process). If an equivalent patch already exists in your Local Storage, it will not be imported, and you will see a message like so:
The SD Card tab gives you a quick way to mass import patches from your SD card into the Librarian, but what about mass exporting? That is where the Banks tab comes into play, which will be discussed in the next section.
Upon navigating to the Banks tab, you will be presented with the following screen:
On the right side of the screen, you can view patches saved within the Librarian. You cannot modify their tags, categories, or patch notes in this view, nor can you delete them. To do so, you will need to go back to the Local Storage tab. You can still view additional patch information and enter the Version History for patches in the Banks tab. You can also search for patches just as you can in the Local Storage View.
To get started, select a patch from the Local table, and either drag it over to a slot in one of the two bank tables, or click the “Add to Bank” button for the patch. Once you have patches in the bank tables, you can move them around in the same way as the SD Card tables. If you add a patch to the bank that has multiple versions contained within it, it will automatically populate the table with all the patches contained within.
Once you are finished making your Bank, you can save it using the “Save Bank” button, and/or export it using the “Export Bank” button. Please note exporting can not occur unless you have specified your SD card. Once you have bank(s) saved, you can use the “Load Bank” button to populate the bank tables with those patches. Please note that if you remove patches from your Local Storage that are within a saved bank, they will not load, as they no longer exist. Finally, there is a “Clear Bank” button for a quick way to clear the bank completely (alternatively, you would remove patches from a bank by clicking the “Remove” button in each row).
Whether you are saving or exporting, you will be asked to provide a name for your Bank:
You will be warned if a folder on your SD card is already using the name you provided. Otherwise, you will be able to find your patch Bank in a new folder on the root of your SD card.
There are some additional features that are available in the Librarian which can apply to multiple tabs. You’ll find these in the menu actions.
The File menu has been discussed previously, in the context of your SD card location. The other items are for when you’d like to import patch files that exist on your local filesystem. Each one is analogous to the functionality in the SD Card tab.
The Sort menu offers ways to sort the various tables in the Librarian. This applies to the PatchStorage, Local Storage, and Bank tabs. Note that sorting by Author is not available in the PatchStorage tab. The default sorting option is by Date (New-Old).
The Options menu is for altering the look and feel of the Librarian, including row inversion, font style and size, dark mode toggle (always on, of course), and a way to 
reset the UI panels and tables to their defaults.
The Help menu is where you’ll find documentation for the Librarian and resources for using the ZOIA. This information will display in the PatchStorage tab on the right-side panel where the patch notes would show. The FAQ is provided below as an example.
Version 1.0 represents the first major release of the Librarian and includes many notable additions, changes, bug fixes, and one known issue.
New Features
Fixes
Known Issues
The app still has a lot of potential for additional features! These include:
We encourage you to provide feedback on things you want to see changed or features you would like to see added! Thank you for being an awesome member of the ZOIA community!